<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>The Fast-Path Interface</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.2 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="libpq - C Library"
HREF="libpq.html"><LINK
REL="PREVIOUS"
TITLE="Canceling Queries in Progress"
HREF="libpq-cancel.html"><LINK
REL="NEXT"
TITLE="Asynchronous Notification"
HREF="libpq-notify.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2011-12-01T22:07:59"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.2 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Canceling Queries in Progress"
HREF="libpq-cancel.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 31. <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> - C Library</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Asynchronous Notification"
HREF="libpq-notify.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="LIBPQ-FASTPATH"
>31.6. The Fast-Path Interface</A
></H1
><P
>   <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> provides a fast-path interface
   to send simple function calls to the server.
  </P
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
>    This interface is somewhat obsolete, as one can achieve similar
    performance and greater functionality by setting up a prepared
    statement to define the function call.  Then, executing the statement
    with binary transmission of parameters and results substitutes for a
    fast-path function call.
   </P
></BLOCKQUOTE
></DIV
><P
>   The function <CODE
CLASS="FUNCTION"
>PQfn</CODE
>
   requests execution of a server function via the fast-path interface:
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQfn(PGconn *conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);

typedef struct
{
    int len;
    int isint;
    union
    {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;</PRE
><P>
  </P
><P
>   The <TT
CLASS="PARAMETER"
>fnid</TT
> argument is the OID of the function to be
   executed.  <TT
CLASS="PARAMETER"
>args</TT
> and <TT
CLASS="PARAMETER"
>nargs</TT
> define the
   parameters to be passed to the function; they must match the declared
   function argument list.  When the <TT
CLASS="PARAMETER"
>isint</TT
> field of a
   parameter structure is true, the <TT
CLASS="PARAMETER"
>u.integer</TT
> value is sent
   to the server as an integer of the indicated length (this must be 1,
   2, or 4 bytes); proper byte-swapping occurs.  When <TT
CLASS="PARAMETER"
>isint</TT
>
   is false, the indicated number of bytes at <TT
CLASS="PARAMETER"
>*u.ptr</TT
> are
   sent with no processing; the data must be in the format expected by
   the server for binary transmission of the function's argument data
   type.  <TT
CLASS="PARAMETER"
>result_buf</TT
> is the buffer in which to
   place the return value.  The caller must  have  allocated sufficient
   space to store the return value.  (There is no check!) The actual result
   length will be returned in the integer pointed to  by
   <TT
CLASS="PARAMETER"
>result_len</TT
>.  If a 1, 2, or 4-byte integer result
   is expected, set <TT
CLASS="PARAMETER"
>result_is_int</TT
> to 1, otherwise
   set it to 0.  Setting <TT
CLASS="PARAMETER"
>result_is_int</TT
> to 1 causes
   <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> to byte-swap the value if necessary, so that it
   is delivered as a proper <TT
CLASS="TYPE"
>int</TT
> value for the client machine.
   When <TT
CLASS="PARAMETER"
>result_is_int</TT
> is 0, the binary-format byte string
   sent by the server is returned unmodified.
  </P
><P
>   <CODE
CLASS="FUNCTION"
>PQfn</CODE
> always returns a valid
   <TT
CLASS="STRUCTNAME"
>PGresult</TT
> pointer. The result status should be
   checked before the result is used.   The caller is responsible for
   freeing  the  <TT
CLASS="STRUCTNAME"
>PGresult</TT
>  with
   <CODE
CLASS="FUNCTION"
>PQclear</CODE
> when it is no longer needed.
  </P
><P
>   Note that it is not possible to handle null arguments, null results,
   nor set-valued results when using this interface.
  </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq-cancel.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq-notify.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Canceling Queries in Progress</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Asynchronous Notification</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>